home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / toolfix.arc / CONST.ACC < prev    next >
Text File  |  1987-03-03  |  13KB  |  239 lines
  1. *******************************************************************************
  2.  
  3.                                    CONST.ACC
  4.                                    Version 1
  5.                                November 6, 1985
  6.                                by Randy Forgaard
  7.                              CompuServe 70307,521
  8.  
  9. This file presents some hints for choosing values for the special constants
  10. required by the Turbo Access portion of the Turbo Pascal implementation of the
  11. Turbo Database Toolbox (formerly the Turbo Toolbox), versions 1.0 and 1.1.  It
  12. applies to all operating systems and computers for which the Database Toolbox
  13. is available.  There are no hard facts in this file that are not also in the
  14. Toolbox manual, but the hints below may help if your program is going haywire
  15. and you suspect that the values of the Turbo Access constants may be the source
  16. of the problem.  These hints might also help increase the speed of Turbo Access
  17. as used by your program.
  18.  
  19. *******************************************************************************
  20.  
  21.  
  22. The Turbo Access portion of the Turbo Database Toolbox asks the programmer to
  23. declare 6 integer constants in the Turbo Pascal program, namely MaxDataRecSize,
  24. MaxKeyLen, PageSize, Order, PageStackSize, and MaxHeight, prior to the {$I}
  25. directives that bring in the Toolbox source files.  Bad values for these
  26. constants can result in anything from poor performance to mysterious program
  27. crashes.  Below, these constants are discussed individually.
  28.  
  29.  
  30.                                 MaxDataRecSize
  31.                                 --------------
  32.  
  33. MaxDataRecSize is the size of the largest record you will be storing in any
  34. DataFile.  That is, if you are going to have two kinds of DataFiles, one to
  35. store records of type R1, and one to store records of type R2, and R2 records
  36. occupy more storage than R1 records, MaxDataRecSize should be set to the number
  37. of bytes occupied by records of type R2.  If MaxDataRecSize is larger than
  38. necessary, Turbo Access will still work properly, but some memory will be
  39. wasted.
  40.  
  41. Suppose that your program is to have two kinds of DataFiles, some of which hold
  42. records of type Person, and some of which hold records of type Loan, where
  43. these record types are defined as follows:
  44.  
  45.   type                                  type
  46.     Person = record                       Loan = record
  47.                name: String[30];                   company: String[40];
  48.                age: Byte;                          secured: Boolean;
  49.                married: Boolean                    months: Integer;
  50.              end;                                  interestRate, payment: Real
  51.                                                  end;
  52.  
  53. MaxDataRecSize must be set to the size of Person or Loan, whichever is larger.
  54. It is dangerous to compute MaxDataRecSize by hand.  For example, in computing
  55. the size of Person, one might say that Person occupies 30 + 1 + 1 = 32 bytes.
  56. But the actual answer is 33 bytes (the String[30] type occupies 31 bytes, due
  57. to the additional byte for the length).  In computing the size of Loan, one
  58. might forget that there are actually two Reals, even though they are listed on
  59. one line.  Furthermore, the number of bytes occupied by a Real could be 6, 8,
  60. or 10 bytes, depending on whether regular Turbo, Turbo-87, or Turbo BCD is
  61. being used.
  62.  
  63. To be sure to pick an appropriate value for MaxDataRecSize, create a little
  64. Turbo program that includes the type definitions for the records you will be
  65. storing in DataFiles, and write out the size of each of those records using
  66. Turbo's built-in SizeOf function, so that you can choose the maximum of those
  67. values.   For the above record types, one could write a program like this:
  68.  
  69.   program DisplaySizes;
  70.  
  71.   <...type definitions of Person and Loan go here...>
  72.  
  73.   begin
  74.     writeln('Size of Person = ', SizeOf(Person));
  75.     writeln('Size of Loan   = ', SizeOf(Loan))
  76.   end.
  77.  
  78. Compile and run this small program under the same version of Turbo that you
  79. will be using for your real program.  Running this program under regular Turbo
  80. gives us 33 bytes for the size of Person, and 56 bytes for the size of Loan.
  81. Under Turbo-87 we get 33 and 60 bytes, respectively, and Turbo BCD yields 33
  82. and 64.  Assuming that we are using regular Turbo, we would set the value of
  83. MaxDataRecSize to 56 (the larger of 33 and 56).  To be safe, in case we decide
  84. to use Turbo BCD in the future and forget to change MaxDataRecSize accordingly,
  85. we might set MaxDataRecSize to 64.
  86.  
  87. It is very important that MaxDataRecSize be the correct value, or larger.  A
  88. value for MaxDataRecSize that is too small results in mysterious and erratic
  89. program behavior, and the cause of the problem can be very difficult to find.
  90.  
  91.  
  92.                                    MaxKeyLen
  93.                                    ---------
  94.  
  95. MaxKeyLen is the length of the longest keys you will be using for any of your
  96. IndexFiles.  In Turbo Access, all keys are strings, and MaxKeyLen is a string
  97. length.  For example, if your longest keys are 25 characters long, you would
  98. use String[25] as the type of any variables that are to hold those keys, and
  99. you would set MaxKeyLen to 25.
  100.  
  101. Note that this is a different idea from MaxDataRecSize.  The obvious difference
  102. is that MaxKeyLen refers to the keys in the IndexFiles, and MaxDataRecSize
  103. refers to the data records in the DataFiles.  The subtle difference is that
  104. MaxKeyLen is the length of the string, _not_ the number of bytes such a string
  105. would occupy.  If your keys are up to 25 characters long, set MaxKeyLen to 25.
  106. However, if a String[25] is part of a data record, the String[25] would have to
  107. be counted as 26 bytes for the purposes of computing MaxDataRecSize.
  108.  
  109.  
  110.                                    PageSize
  111.                                    --------
  112.  
  113. PageSize is the number of key entries in each page of every IndexFile used by
  114. your program.  It must be an even number between 4 and 254, inclusive.  Beyond
  115. this restriction, it is difficult to choose a "correct" value for PageSize; it
  116. is a performance/space trade-off, and a non-linear one at that.  If you choose
  117. a value for PageSize that is too small, Turbo Access will have to traverse many
  118. IndexFile pages during a search, which usually means of a lot of disk I/O.  A
  119. value for PageSize that is too large will use up a lot of memory without
  120. yielding a proportionately larger increase in execution speed.
  121.  
  122. The issue is further complicated in that a single value for PageSize must be
  123. chosen that will be used for all IndexFiles in your program, even though
  124. different PageSize values will be optimal for IndexFiles with different maximum
  125. key lengths.  For the purpose of choosing a PageSize value, identify the
  126. IndexFile whose access speed is most critical to your application.  In what
  127. follows, let K denote the maximum key length of that IndexFile.
  128.  
  129. Some tests with Turbo Access, on both a hard disk and a floppy, seem to suggest
  130. the following rule of thumb for achieving good time/space efficiency: Choose
  131. PageSize so that the product of PageSize and K is close to 2000.  Smaller
  132. values for PageSize can cause Turbo Access to run measurably slower.   Larger
  133. values for PageSize will use up valuable memory space that could be more
  134. profitably used by increasing PageStackSize (see below), rather than PageSize.
  135.  
  136.  
  137.                                      Order
  138.                                      -----
  139.  
  140. The value of Order is simply half of the value of PageSize.  Since PageSize is
  141. always even, Order will be an integral value.  The name "order," in the
  142. terminology of trees, refers to the number of children each node of the tree
  143. has.  A binary tree is order 2.  In B+ trees, the number of children varies,
  144. but is always at least half of the PageSize.  Hence the name Order for half of
  145. PageSize.
  146.  
  147.  
  148.                                  PageStackSize
  149.                                  -------------
  150.  
  151. PageStackSize is the number Pages that Turbo Access keeps internally, as a
  152. cache, so that it does not need to read pages from disk as often.  The value of
  153. PageStackSize must be greater than or equal to 3.  The Toolbox manual notes
  154. that the "minimum reasonable value for PageStackSize is the value of MaxHeight"
  155. (see below).  Indeed, empirically, extraordinary performance degradation does
  156. seem to result if PageStackSize is less than MaxHeight.
  157.  
  158. Like PageSize, the choice of a value for PageStackSize is a performance/space
  159. trade-off.  Larger values for PageStackSize will allow Turbo Access to run
  160. faster, but will also use more of the memory that the Turbo compiler sets aside
  161. for global variables in your program.  After PageSize has been chosen as per
  162. above, choose the largest possible value for PageStackSize that will still
  163. permit the rest of your program to have the memory for global variables that it
  164. needs.  This may be a trial-and-error process, since large values for
  165. PageStackSize may cause a "Memory Overflow" error from Turbo while compiling
  166. global variable declarations in either the Turbo Access source files or in your
  167. own code.
  168.  
  169.  
  170.                                    MaxHeight
  171.                                    ---------
  172.  
  173. MaxHeight is the maximum height that the B+ tree in any IndexFile can attain.
  174. It is a function of the PageSize and the maximum number of keys (including
  175. duplicates, if permitted) that you will allow in any of the IndexFiles your
  176. program uses.  You can find the correct value for MaxHeight by running the
  177. following Turbo program, which implements the MaxHeight formula given in the
  178. Toolbox manual:
  179.  
  180.   program FindMaxHeight;
  181.   var
  182.     PageSize, MaxHeight: Integer;
  183.     MaxKeyCount: Real;
  184.   begin
  185.     write('PageSize: ');
  186.     readln(PageSize);
  187.     write('Maximum number of keys that can be stored in any IndexFile: ');
  188.     readln(MaxKeyCount);
  189.     MaxHeight := Round(Ln(MaxKeyCount) / Ln(PageSize * 0.5)) + 1;
  190.     writeln('MaxHeight = ', MaxHeight)
  191.   end.
  192.  
  193. Increasing MaxHeight by one only adds 4 bytes to each IndexFile variable your
  194. program maintains.  Thus, just in case you underestimate the maximum number of
  195. keys that will be stored in any IndexFile, you might want to add one or two
  196. onto the value of MaxHeight computed by the above program.
  197.  
  198.  
  199.                  General Notes
  200.                  ------- -----
  201.  
  202. After selecting values for the above constants, compiling your program, and
  203. creating database files with those constant values in force, it is possible
  204. that you might want to change those constant values.  With MaxDataRecSize,
  205. MaxKeyLen, PageStackSize, and MaxHeight, you can change the constant (subject
  206. to the constraints stated in the paragraphs above), recompile your program, and
  207. still be able to read IndexFiles that were created under the old constant
  208. values.
  209.  
  210. After changing PageSize and Order, however, you will no longer be able to read
  211. IndexFiles created with the old values for PageSize and Order.  In this case,
  212. you will have to rebuild the IndexFiles with the new values for PageSize and
  213. Order in effect.
  214.  
  215. To rebuild IndexFiles, you can always read an old DataFile, "d," by doing a
  216. GetRec(d,i,r) for each data record number "i" from 1 to FileLen(d)-1, and
  217. bypass the IndexFiles entirely.  However, you will need to make sure that you
  218. have reserved the first two bytes of each data record, so that you can tell
  219. whether it has been deleted when reading it with GetRec.  When rebuilding
  220. IndexFiles, you will want to skip any data records marked as deleted.  See the
  221. "Reuse of Deleted Data Records" section of the Toolbox manual for details.
  222.  
  223. Finally, some notes about the versions of Database Toolbox and their
  224. compatibility with the versions of Turbo:
  225.   (1) If you are using DOS Turbo 3.0, make sure you have Turbo 3.01A or later
  226.       (version 3.00B does not work with Turbo Access).
  227.   (2) If you are using DOS Turbo 3.0, make sure you use ACCESS3.BOX in place of
  228.       ACCESS.BOX.  ACCESS3.BOX is included on the Turbo 3.0 disk (not the
  229.       Database Toolbox disk).
  230.   (3) If you have version 1.0 of the Database Toolbox, see the file TBXFIX in
  231.       DL 1 of the Borland SIG on CompuServe, to upgrade your Toolbox to
  232.       version 1.1 (fixes some bugs).
  233. If you are not running under DOS, or if you are using Turbo 2.0, only (3) above
  234. applies to you.
  235.  
  236. If you have any further questions about Turbo Access, or would like to discuss
  237. some aspect of it, please feel free to ask on CompuServe's Borland SIG, and/or
  238. to send a message to me personally on the Borland SIG or via EasyPlex.